Please visit the website listed above for more information and to make sure you have the latest version!
Online registration is available at <http://kagi.direct.net/cgi-bin/register1.cgi?TI>
Contents
- What's New.
- Gray Council Overview.
- Overview of the Gray Council core classes.
- Compatibility.
- Change History.
- Licensing Requirements.
What's New.
Version 1.2.1 is a number of tweaks and fixes. Most are related to resizing and subview targeting in tab panels.
Gray Council Overview.
The Gray Council classes implement the "Apple Grayscale Appearance" for System 7. Apple has published the visual specifications for grayscale user interface components under System 7 that are consistent with the MacOS 8 Appearance Manager default theme. But it is a lot of work to actually implement these specifications; that's what The Gray Council does for you by providing a complete set of core C++ classes that implement the AGA, plus a set of "adapter" classes for MacApp and PowerPlant programmers that make it really easy to add.
The core Gray Council classes are provided in GrayCouncil.cpp and GrayCouncil.h. These classes are not framework-specific. In addition to implementing the complete set of Apple Grayscale Appearance controls, the Gray Council classes provide several additional features that you can take advantage of, or ignore:
- Automatic radio button group mutually exclusive behavior.
- "Live" scrolling; turned on by default.
- Proportional scroll bars; turned off by default.
- Icon buttons with dual-state icons.
- Text style support for non-system font controls.
- Script Manager support for system justification.
- Left- and right-justified sliders.
- "Moving origin" for determinate progress indicators.
- Automatic "quantizing" of indeterminate progress indicators.
In addition to the core Gray Council classes, there are MacApp and PowerPlant adapter classes:
- The MacApp adapter classes are provided in GrayCouncilMA.cpp and GrayCouncilMA.h. These classes provide drop-in MacApp view and adorner subclasses that interface with the core classes. For MacApp users, this means you can for the most part add the Apple Grayscale Appearance by simply changing subview class names in your view resources. There is a separate information file for the MacApp adapter classes, and there is a MacApp 3.3-based sample/test application in the projects folder.
- The PowerPlant adapter classes are provided in GrayCouncilPP.cpp and GrayCouncilPP.h. These classes provide drop-in PowerPlant pane and attachment subclasses that interface with the core classes. For PowerPlant users, this means you can for the most part add the Apple Grayscale Appearance by simply changing pane class IDs in your view resources. There is a separate information file for the PowerPlant adapter classes, and there is a PowerPlant 1.5-based sample/test application in the projects folder.
The Gray Council release 1.3 is nearly complete and will add Dialog Manager adapter classes to help make your dialogs and alerts AGA-compatible. It will also support the newer MacApp "r" release class interfaces.
Please read the licensing requirements section below.
Many thanks for feedback and bug reports to: Jordan Zimmerman, Mike Fischer, Jonathan Kew, Geoff Clapp, Paul Carnine, Nick Nallick, Tom Bayley, Paul Rekieta, Bob Barnes, Andy Bettis, Matt Gieselman, Steve Webster, Luc Heinrich, Mike Shields, Bill Kirtley, Marco Sandri, Don Swatman, Luis Vallecillo, Ken Victor, Tom Hopkins, Malcom Pradhan, Stephen Ju.
Overview of the Gray Council Core classes.
These are the AGA classes that you'll be using for the most part. See GrayCouncil.h for usage instructions. If you are using the MacApp or PowerPlant adapter classes, you will probably not instantiate core class objects directly (although you certainly can).
AGAStaticText
Simple text object that knows how to dim and erase on a gray background.
AGAPushButton
Standard push button control, with optional default button outline.
AGACheckBox
Standard check box control, with mixed-state capability.
AGARadioButton
Standard radio button control, with mixed-state capability.
AGAIconPushButton
Standard icon button control, with push button behavior. Supports icon family, cicn, and PICT resources.
AGAIconCheckBox
Standard icon button control, with check box behavior. Supports icon family, cicn, and PICT resources.
AGAIconRadioButton
Standard icon button control, with radio button behavior. Supports icon family, cicn, and PICT resources.
AGAScrollBar
Standard scroll bar control, with options for live scrolling and proportional thumb.
AGASlider
Standard slider control, labeled or unlabeled, horizontal or vertical, left- or right-oriented, with options for live tracking and proportional indicator.
AGAPopupMenu
Standard popup menu control, with choice of horizontal resizing behavior.
AGALittleArrows
Standard little arrows control.
AGADisclosureTriangle
Standard disclosure triangle, with automatic animation.
AGAProgressIndicator
Standard determinate and indeterminate progress indicators, with option for moving determinate origin.
AGASeparator
Standard separator line.
AGAGroupBox
Standard primary and secondary group boxes, with or without a title, or with gap for separate title object.
AGATabPanel
Standard tab panel, with or without box frame, in small or large tab format.
Some useful functions
- SetGrayCouncilDefault. Lets you turn global GC settings off and on.
- AGAStringOut. Draws a single line of text with truncation, style, and coloring options.
- AGATextBox. Draws a text with line wrapping like TETextBox, with style and coloring options.
- AGABackgroundPaint. Paints a window background of the specified kind.
- AGAInstallGrayWCTB. Installs an r2 gray ramp as the window's 'wctb' background.
- AGADrawBorderFrame. Draws a shaded "3D" sunken border frame around an area, with optional notch.
Compatibility.
The Gray Council classes require Color QuickDraw, and support multiple screen devices including 1-bit drawing and spanning.
Version 1.1 has been tested using CodeWarrior 10 compiling for 68K and PowerPC, using the supplied MacApp and PowerPlant test programs. The MacApp test program uses application main and resource file names as expected by the MPW MABuild tool, although I have only built it with CodeWarrior.
Change History.
1.2.1, November 7 1996.
• The Dialog Manager adapter classes slated for version 1.3 are basically done, but not quite, and I wanted to get these fixes to version 1.2 out first.
- Sample projects are now built with CodeWarrior 10.
- Added GetValue/SetValue methods to core AGAObject for Dialog Manager adapter use.
- Removed SetGroupID from core MExclusiveObject and AGARadioButton classes.
- Added new AGATextBox core function for static text and Dialog Manager adapter use. This function behaves like TETextBox.
- Core AGAStaticText class now uses AGATextBox output function.
- Changed declaration of AGATabPanelPP::GetValue to const.
- Added this->ApplyForeAndBackColors() to PP window & dialog FinishCreate after setting bg color. Was causing static text to incorrectly draw a white background in some circumstances.
- Added this->IsVisible() test before redraw in many MacApp adapter classes.
- Added notification routines to slider adapter classes. You can now just be a listener to sliders.
- PP and MA adapters for icon push buttons/check boxes/radio buttons now respect the pane resource's initial enable setting.
- PP and MA adapters for icon check boxes/radio buttons now respect the pane resource's initial value setting.
- Changed AGADialogBoxPP default button handling so frame goes inside button pane. This prevents bad redrawing of the default button when it is moved or resized.
- PP tab panel adapters are now implemented via Show/Hide, not PutInside. Container view is now inset 4, not 3. Affects LinkListenerToControls usage!
- PP tab panel adapters now support panel resizing & frame binding.
- MA tab panel adapters now better handle target view activation/deactivation handling.
- MA tab panel adapters now support resizing.
- Added AGAPanelEnclosurePP for target switching. If you have targetable panes inside your tab panels, you will probably want to make the enclosing root view of your individual panel PPob's an AGAPanelEnclosurePP.
- Changed redraw to kDontRedraw for MA scroll bar adapter SetLongVal.
- Changed AGAPopupMenuPP to honor the popup title justification.
- Fixed AGAListBoxPP to honor the text style of the list.
- Tweaked location of checkbox & radio buttons & labels by (2,2) to match the positioning used by the system CDEF.
- Fixed AGAActiveScrollerPP instantiation bug (non-virtual during constructor).
- Added custom pane types to GCCustomPaneTypes.rsrc for all non-PPX types.
- Fixed AGATextEditPP. Now part of the text field test panel.
- Fixed hidden virtual AGATargetBorderFrameViewMA::Dim() and AGANotchedTargetBorderFrameViewMA::Dim().
1.2, September 4 1996.
• Implements "tab panels" as specified in the revised 7/96 AGA spec.
• Conforms to the revised 7/96 AGA spec:
- Inactive window backgrounds are flat.
- Dimmed pushbuttons, icon buttons, check boxes, sliders, popup menus, little arrows, group boxes, and border frames are flat.
- Dimmed radio buttons are flat. (I'm deviating ever-so-slightly from the spec to avoid the ugly chunky pixel circle outlines for both enabled and dimmed radio buttons that were re-introduced in the latest spec.)
- Little arrows have rounded corners.
• Changes and bug fixes:
- Turned on full warning errors in test projects; commented out unused parameters. No more warnings!
- Added necessary includes for compiling sans precompiled headers for PowerPlant.
- Changed TRUE/FALSE to true/false for include simplification.
- Bug fix: AGAPopupMenuPP and AGAPopupMA were not setting the initial item number.
- Bug fix: AGAGroupBox was not using the specified font info when calculating the title gap.
- Bug fix: MIconButtonObject was not setting the fore color to black before plotting, which was a problem for icon families with only a 1-bit icon.
- Bug fix: core classes were not checking mEnabled before tracking mouse, and were instead relying on the adapter classes to always check the enable state.
- Replaced CleansePen with a stack-based AGADrawingEnvironment class. It is being used in many places to save, clean, and restore the drawing environment.
- Bug fix: AGAPopupMenu was always drawing the popup arrow assuming a standard size popup.
- Changed AGAStaticTextMA::CreateAGAObject to use fDimmed instead of !fEnabled, since for static text disabled and dimmed are distinct attributes.
- Changed other MacApp CreateAGAObject functions to use fDimmed || !fEnabled.
- Added MacApp SetEnable overrides to enable/disable on the fly.
- Bug fix: AGASecondaryGroupBox was failing to use the gap pane.
- Bug fix: AGACaptionPP was not strictly a drop-in replacement for LCaption. Changed to use LCaption method of drawing text.
- Replaced all calls to PLstrcpy with AGA_PLstrcpy, so that the plstringfuncs library is no longer needed.
- Renamed color ramp indexes to match AGA revision: rA1-4 become rP1-4, rename rA to rA1, add new rA2.
- Made AGAPushButtonMA inset the core object bounds by 1x1 if it has a default outline, because the AGA default outline is 3x3 extra around the button instead of 4x4.
- Implemented AGAPopupMenu support for custom popup menu font/size. There is one problem left: with PowerPlant, the font is respected but the font size for the popped-up menu isn't always respected. This problem does not seem to occur with MacApp.
- Added support for "notched" white backgrounds, border frames, target borders, etc. These can be used where you want the thing to be contoured around the notch below and to the right of a pair of scroll bars, where a grow box would be if at the absolute edge of the window.
- Changed AGAScrollerPP to be set for non-live scrolling, so that it behaves strictly as a drop-in replacement for LScroller.
- Added a class AGAActiveScrollerPP, a new scroller subclass set for live scrolling. This can be used as a drop-in replacement for LActiveScroller.
- Changed core MIconButtonObject to support cicn and PICT images, and explicit setting of frame and image types
- Changed PowerPlant icon button adapters and custom pane types changed to reflect new MIconButtonObject capabilities.
- Bug fix: the MacApp and PowerPlant popup menu label text style was not being respected.
- AGADisclosureTrianglePP now does a SetValue to cause a value message broadcast just like the others.
- Removed the Standard Template Library-based code for mutually exclusive groups in core, re-implemented without STL, to avoid excess inclusion and external library requirements.
- Changed AGAProgressIndicator and adapter classes so that they are capable of indeterminate idling all by themselves. You don't have to manage the idling other than start/stop; and if you set the mUserCon or fUserArea to non-zero, it will start itself idling. The idling is quantized for a constant rate of animation.
- Added marker pragmas to header files for easier navigation.
- Added test in PowerPlant adapters for this->IsVisible before passing kRedraw to mAGAObject, so that drawing is prevented while a pane is being created but still invisible.
- Changed AGAObject so that it has a pair of background color values instead of a single one. This is because tab panels have an r1 background when enabled, r2 when disabled. So any objects inside a tab panel need to draw their own background differently depending on whether they're enabled or disabled.
- Added default constructors to all PP pane adapter classes. Not sure how this will work -- let me know.
- Bug fix: the PowerPlant adapter SetValue overrides were calling inherited and then passing the input parameter to the core object. But the input parameter can become stale if the inherited call causes a recursive SetValue (such as via a broadcast). So the fix is to use the mValue after calling inherited, rather than the input value.
- Changed AGASliderPP to keep the LControl min/max in sync with slider range as it is created.
- AGAEditFieldPP revamped -- drawing not sufficient for dimming & tab panel dual colors.
- AGAListBox revamped -- drawing not sufficient for dimming & tab panel dual colors.
- Changed AGAScrollBar to make sure indicator changes are not draw when the scroll bar is inactive.
- Changed AGALittleArrowsPP to prevent extra flicker of linked edit field after mouse tracking.
1.1.1, August 12 1996.
• Changes and bug fixes from initial PowerPlant release feedback:
- Bug fix: GDIterator was using GetMainDevice instead of GetDeviceList to get 1st device.
- Bug fix: added ResizeFrameBy and MoveBy overrides to PowerPlant adapters to allow moving/resizing the AGA objects.
- Changed test applications to resize some buttons in the main window when you resize the window. This is to do a rudimentary test of the object resizing code.
- Bug fix: added SetDescriptor override to AGAGroupBoxPP to catch changing group box title on the fly.
- Bug fix: added SetText/SetTitle overrides to MacApp adapters where missing to catch title changes.
- Bug fix: fixed typo of no-twice-include symbol in GrayCouncilPP.h.
- Added "#pragma once" to header files.
- Created AGAFlatBackgroundBehaviorMA to set 'wctb' gray background in window. This should probably now be used instead of AGAModalBackgroundAdornerMA for movableDBoxProc and dBoxProc windows, unless you like the white border inside the window.
- Changed AGAWindowPP and AGADialogBoxPP to be smarter about the window background. In particular, AGADialogBoxPP will now notice movableDBoxProc and dBoxProc windows, and use 'wctb' gray background to eliminate the white border inside the window.
- Created AGAWindowPPX and AGADialogBoxPPX for use with custom pane types, only needed if you want to change the background type determined by the superclass. The background type IDs are defined by the AGABackgroundKind enum in GrayCouncil.h.
- Bug fix: AGAScrollBar was not properly enabling/disabling itself when the range toggled between 0 and non-zero. The test apps now have radio buttons to toggle between a big picture and a small picture, which causes this implicit state change.
- Bug fix: previous AGAScrollBar off-by-1 thumb range bug was not completely solved. Now it is.
I think these scroll bar fixes make the scroll bars solid. I have exercised them quite a bit in a real-world app.
1.1, August 9 1996.
• Implements PowerPlant adapter classes.
• Implements the following changes and bug fixes:
- Made offscreen image RGB bit manipulation OK for 2-byte int builds (as in PowerPlant project stationery).
- Made AGAStringOut force text mode to srcOr so as not to erase background in PowerPlant drawing environment.
- Moved window background drawing from MacApp adorners to core AGA function call.
- Added two #pragma segment directives to GrayCouncil.cpp because the core segment size was too big for the PowerPlant project stationery's default code model settings.
- Bug fix: AGALittleArrows::mNotificationRoutine was not inited to NULL!
- Bug fix: variable-width menu sizing was using a Max calc instead of Min.
- Bug fix: popup label was too close to popup (MacApp demo had somehow gotten trailing spaces in the labels to hide the error). Now inset label box right by 3.
- Bug fix: the indeterminate progress indicator's GDIterator was being destructed after restoring the clip, causing clipping problem with multi-screen drawing in PowerPlant drawing environment.
- Made core draw routines set up pen completely before drawing. There are too many framework-dependent drawing environment differences to assume anything.
- Implemented window/dialog background shading contoured around grow box. The test apps now use a resizeable main window to demonstrate this.
- Bug fix: bottom right edge pixels needed to be redrawn to handle resizeable windows. The adapter classes now override the necessary window resize functions to catch this and redraw as necessary. The test apps now use a resizeable main window to demonstrate this.
For commercial or in-house developer use, you must register a copy of The Gray Council for each developer. If you have several developers using the Gray Council code, you may prefer to simply register a site license.
You may modify this code for your own purposes, but you may not redistribute modified versions of this code, and you are still subject to the licensing requirements even if you modify this code. This code is provided as-is, and is not warranted for suitability to any particular purpose. Use at your own risk.
Registration is done using the Kagi Shareware service—use the supplied Register application if you are registering. With your registration, please note the name of your application.
•New as of version 1.2: online registration! You can now register even more easily by visiting:
<http://kagi.direct.net/cgi-bin/register1.cgi?TI>
If you have any questions about licensing, e-mail me at <trygve@bombaydigital.com>
Using the Register program.
[ Below are the instructions from Kagi on using the shareware registration program. ]
Open the Register program. Enter your name, your email address, and the number of single user licenses you desire for each program you wish to purchase (or Site or Word-Wide licenses). Save or Copy or Print the data from the Register program and send the data and payment to Kagi. More specifics on the Register program to follow. Kagi handles the payment processing.
If paying with Credit Card or First Virtual, you can email or fax the data to Kagi. Their email address is sales@kagi.com and their fax number is +1 510 652-6589. You can either Copy the data from Register and paste into the body of an email message or you can Save the data to a file and you can attach that file to an email message. There is no need to compress the data file, it's already pretty small. If you have a fax modem, just Print the data to the Kagi fax number.
Payments sent via email are processed within 3 to 4 days. You will receive an email acknowledgement when it is processed. Payments sent via fax take up to 10 days and if you provide a correct internet email address you will receive an email acknowledgement.
If you are paying with Cash or USD Check you should print the data using the Register application and send it to the address shown on the form, which is:
Kagi
1442-A Walnut Street #392-TI
Berkeley, California 94709-1405
USA
You can pay with a wide variety of cash from different countries but at present if you pay via check, it must be a check drawn in US Dollars. Kagi cannot accept checks in other currencies, the conversion rate for non-USD checks is around USD 15 per check and that is just not practical. If you have a purchasing department, you can enter all the data into the Register program and then select Invoice as your payment method. Print three copies of the form and send it to your accounts payable people. You might want to highlight the line that mentions that they must include a copy of the form with their payment.
Kagi can not invoice your company, you need to act on my behalf and generate the invoice and handle all the paperwork on your end. Please do not fax or email payment forms that indicate Cash, Check or Invoice as the payment method. As far as we know, there is still no technology to transfer physical objects via fax or email and without the payment, the form cannot be processed. Payments send via postal mail take time to reach Kagi and then up to 10 days for processing. Again, if you include a correct email address, you will hear from Kagi when the form is processed.
